docs: Updating !include documentation for clarity #1496
Conversation
There was a problem hiding this comment.
Thanks for taking the initiative to improve our docs, @badge! 🙏
Would you mind elaborating a little, what specifically you were struggling with when trying to use !include? What part of the syntax do you consider restrictive and didn't get right immediately? Using the YAML document markers correctly?
I'm asking because your content change – besides some rearranging of text blocks – is this:
+The syntax of a single include is:
+
+```yaml
+---
+!include filename.yml
+---
+```
+
+the `---` on new lines are essential, but you don't need to duplicate them if you have
+two `!include` directives.
+
+!!! hint
+
+ When working with multiple documents, you can use [`exclude`][exclude]
+ to exclude them from the rendered project.Honestly, I don't find these explanations very intuitive.
-
A single
!includedirective does not need to be surrounded by---. Instead, the contents of multiplecopier.ymlfiles must be placed in separate YAML documents, which are separate by---markers. Also, a document start marker (i.e., a YAML file beginning with---) is optional. For instance, the followingcopier.ymlfiles are all valid:-
!include common.yml -
--- !include common.yml
-
!include common.yml --- custom_question: default answer
-
--- !include common.yml --- custom_question: default answer
-
!include common1.yml --- !include common2.yml
-
custom_question1: default answer --- custom_question2: default answer
-
...
-
-
+the `---` on new lines are essential, but you don't need to duplicate them if you have +two `!include` directives.
Are you trying to say that the two subsequent
---in--- !include common1.yml --- # <--- duplicates --- # <--- duplicates !include common2.yml ---
aren't necessary? In fact, they aren't allowed because between those two subsequent
---markers is an empty YAML document which Copier doesn't allow. Also, the document end marker---at the bottom isn't allowed. We could look into handling empty YAML documents gracefully instead of raising an error. In any case, I don't find the explanation clear and helpful, especially when the concept of YAML documents is known. -
+!!! hint + + When working with multiple documents, you can use [`exclude`][exclude] + to exclude them from the rendered project.
What do you mean? Unless I'm missing something, I think the existing documentation says all there is to say, i.e. the
excludelists from each document are concatenated. What does "them" in "[...] to exclude them [...]" refer to?
docs/configuring.md
Outdated
| !include copier-other.yml | ||
| ``` | ||
|
|
||
| This is invalid twice over: we haven't put the `!include` directive at the top |
There was a problem hiding this comment.
How about just demonstrating and immediately annotating the correct syntax:
!include copier-other.yml
---
Please note that the !include directive MUST be the first line in the file.
The line after the directive must contain only three dashes and a newline character as shown above.
Anything else is invalid and will not work.
There was a problem hiding this comment.
Please note that the
!includedirective MUST be the first line in the file.The line after the directive must contain only three dashes and a newline character as shown above.
Anything else is invalid and will not work.
That's not correct. The !include directive can appear anywhere in copier.yml as long as it's placed in a separate YAML document. For instance:
copier.yml;q1: hello --- !include q2.yml
q2.yml:q2: world
There was a problem hiding this comment.
Ah, so the first example like this:
!include copier-other.yml
---actually works because the !include is in the implicit "first document" and the -- marks the end of the first contained document and the beginning of the second.
Can there also be any number of !includes in the file, as long as there's only one per document?
Is this valid?
--- # explicit, optional "start of first document"
!include include1.yml
--- # end first, begin second document
!include include2.yml
--- # end second, begin third document
!include include3.yml
--- # and so forth...
|
@sisp ha, so I tried and clearly failed to open an MR to be helpful, but as you point out the change I proposed was also ambiguous. Perhaps it's better to explain what I understood from the docs as they are. I assumed I could just do something like this: use_docker:
type: bool
help: Include a Dockerfile?
default: true
!include copier-docker.yml
use_fortran:
help: Include build tools for Fortran?
default: trueWhat I didn't undestand from the docs was that the |
|
No worries, @badge, it's a good discussion anyway! 👌 So, how about improving clarity by referring more explicitly to YAML documents, perhaps with a link to the official documentation, explaining the need for the document end marker |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #1496 +/- ##
=======================================
Coverage 97.46% 97.46%
=======================================
Files 48 48
Lines 4537 4537
=======================================
Hits 4422 4422
Misses 115 115
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
I just had a hell of a time trying to get
!includeworking, and hadn't realised how restrictive the syntax is. This PR clarifies the documentation on includes to prevent future misunderstandings!